Data Value Manipulation (FlipEnd)(OD Cookbook)

Inside Macintosh: OpenDoc Cookbook / Part - Appendixes: Appendix A - OpenDoc Utilities

Data Value Manipulation (FlipEnd)
This section describes the utilities defined in the files FlipEnd.h and FlipEnd.cpp. These routines are used to convert between big-endian (most-significant byte first) and little-endian (least-significant byte first) data values, which may be required for cross-platform data storage.
The utility assumes that big-endian platforms define the compiler switch _PLATFORM_BIG_ENDIAN. The standard format for the functions and macros defined in the utility is little endian. Therefore, using the utility to coerce data into standard format means you are writing data in little-endian format.

Conversion Functions
The following functions convert the indicated types of values to the opposite endian format in memory. Clients typically do not use these functions directly, because they always swap bytes, whether it is appropriate to do so or not on the current platform. Instead, clients normally use the macros (described in the following section) that convert to and from standard format.

ODFlipShort
The ODFlipShort function takes as a parameter a single 2-byte integer and returns the value with the opposite endian format. The prototype of this function appears as follows:
ODUShort ODFlipShort(ODUShort n);
ODFlipShortArray
The ODFlipShortArray function takes as parameters a pointer to an array of 2-byte integers and a count of the number of integers in the array. The function converts the endian format of each integer in the array. The prototype of this function appears as follows:
void ODFlipShortArray(ODUShort* a, unsigned long count);
ODFlipLong
The ODFlipLong function takes as a parameter a single 4-byte integer and returns the value with opposite endian format. The prototype of this function appears as follows:
ODULong ODFlipLong(ODULong n);
ODFlipLongArray
The ODFlipLongArray function takes as parameters a pointer to an array of 4-byte integers and a count of the number of integers in the array. The function converts the endian format of each integer in the array. The prototype of this function appears as follows:
void ODFlipLongArray(ODULong* a, unsigned long count);
ODFlipStruct
The ODFlipStruct function takes as parameters a pointer to a C++ structure and a pointer to a zero-terminated array of short integers. The prototype of this function appears as follows:
void ODFlipStruct(void* structure, const short* groups);
This function inverts the endian format of the contents of memory in the structure parameter, according to the layout described by the groups parameter. The groups parameter points to a zero-terminated array of shorts, where each short describes the size of the next chunk of memory in the structure to be processed. A negative value -n in the groups array indicates a block of endian-neutral memory, such as a string, and causes n bytes of memory to be skipped over. A positive value n in the groups array indicates a block of n bytes of memory that should have its bytes flipped end for end. Only positive values in the set { 2, 4, 8 } are handled. (Other positive values are handled like negative values: blocks of memory are skipped).
Here is an example of a structure and the groups array indicating how it should be converted:
struct snod {
long  beta;
char  gamma[8];
long  delta;
short alpha;
};
const short snodGroups[] = {
4, // beta
-8, // gamma 
4, // delta
2, // alpha
0, // zero-termination
};
Conversion Macros
The following macros convert to and from standard (little-endian) format. The macro definitions show what the macros do in terms of the functions described in the previous section. The #define statements following the #ifdef conditional define the macros for big-endian platforms; the statements following the #else conditional define the same macros correctly for little-endian platforms.
#ifdef _PLATFORM_BIG_ENDIAN_
   
#define ConvertODUShortToStd(n)        ODFlipShort(n)
#define ConvertODUShortFromStd(n)      ODFlipShort(n)
   
#define ConvertODSShortToStd(n)        \
                  ((ODSShort) ODFlipShort((ODUShort) n))
#define ConvertODSShortFromStd(n) \
                  ((ODSShort) ODFlipShort((ODUShort) n))
   
#define ConvertODULongToStd(n)         ODFlipLong(n)
#define ConvertODULongFromStd(n)       ODFlipLong(n)
      
#define ConvertODSLongToStd(n)         \
                  ((ODSLong) ODFlipLong((ODULong) n))
#define ConvertODSLongFromStd(n)       \
                  ((ODSLong) ODFlipLong((ODULong) n))

#define ConvertODStructToStd(s, g)     ODFlipStruct((s),(g))
#define ConvertODStructFromStd(s, g)   ODFlipStruct((s),(g))

#define ConvertODUShortArrayToStd(a,c)    ODFlipShortArray((a),(c))
#define ConvertODUShortArrayFromStd(a,c)  ODFlipShortArray((a),(c))

#define ConvertODSShortArrayToStd(a,c)   \
                  ODFlipShortArray((ODUShort*)(a),(c))
#define ConvertODSShortArrayFromStd(a,c) \
                  ODFlipShortArray((ODUShort*)(a),(c))

#define ConvertODULongArrayToStd(a,c)     ODFlipLongArray((a),(c))
#define ConvertODULongArrayFromStd(a,c)   ODFlipLongArray((a),(c))

#define ConvertODSLongArrayToStd(a,c)    \
                     ODFlipLongArray((ODULong*)(a),(c))
#define ConvertODSLongArrayFromStd(a,c)  \
                     ODFlipLongArray((ODULong*)(a),(c))

#else
   
#define ConvertODUShortToStd(n)        (n)
#define ConvertODUShortFromStd(n)      (n)
   
#define ConvertODSShortToStd(n)        (n)
#define ConvertODSShortFromStd(n)      (n)
   
#define ConvertODULongToStd(n)         (n)
#define ConvertODULongFromStd(n)       (n)
      
#define ConvertODSLongToStd(n)         (n)
#define ConvertODSLongFromStd(n)       (n)
      
#define ConvertODStructToStd(s, g)     /* do nothing */
#define ConvertODStructFromStd(s, g)   /* do nothing */

#define ConvertODUShortArrayToStd(a,c)    /* do nothing */
#define ConvertODUShortArrayFromStd(a,c)  /* do nothing */

#define ConvertODSShortArrayToStd(a,c)    /* do nothing */
#define ConvertODSShortArrayFromStd(a,c)  /* do nothing */

#define ConvertODULongArrayToStd(a,c)     /* do nothing */
#define ConvertODULongArrayFromStd(a,c)   /* do nothing */

#define ConvertODSLongArrayToStd(a,c)     /* do nothing */
#define ConvertODSLongArrayFromStd(a,c)   /* do nothing */

#endif /* _PLATFORM_BIG_ENDIAN_ */